Skip to content

docs: adopt Diátaxis framework for user documentation#32

Merged
zircote merged 5 commits intomainfrom
docs/diataxis-framework
Feb 16, 2026
Merged

docs: adopt Diátaxis framework for user documentation#32
zircote merged 5 commits intomainfrom
docs/diataxis-framework

Conversation

@zircote
Copy link
Owner

@zircote zircote commented Feb 16, 2026

Summary

Adopts the Diátaxis documentation framework to add structured learning paths for NSIP users. The repository had excellent technical reference docs but lacked learning materials for newcomers.

Changes

  • Tutorials: Getting Started guide (15-minute hands-on introduction)
  • How-To Guides: Configure Client, Compare Animals
  • Explanation: Understanding EBVs (breeding value concepts)
  • Reference: Error Handling (complete error type reference)
  • Infrastructure: Updated docs/README.md, added ADR-0003

New Documentation Structure

docs/
├── tutorials/          # Learning-oriented guides (NEW)
├── how-to/             # Problem-oriented guides (NEW)
├── explanation/        # Understanding-oriented discussions (NEW)
├── reference/          # Information-oriented technical docs (NEW)
├── runbooks/           # Operational procedures (existing)
├── template/           # Template adoption guides (existing)
└── workflows/          # CI/CD documentation (existing)

Closes #30

Generated by the Update Docs agentic workflow.

@github-actions
Copy link
Contributor

Benchmark Results

No benchmarks configured. Add benchmarks to benches/ directory.

Full results available in CI artifacts.

@codecov
Copy link

codecov bot commented Feb 16, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.83%. Comparing base (2e68126) to head (73268ae).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main      #32   +/-   ##
=======================================
  Coverage   95.83%   95.83%           
=======================================
  Files           9        9           
  Lines        6499     6499           
=======================================
  Hits         6228     6228           
  Misses        271      271           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@github-actions
Copy link
Contributor

Code Coverage Report

Overall Coverage: 0%

Summary

Filename                      Regions    Missed Regions     Cover   Functions  Missed Functions  Executed       Lines      Missed Lines     Cover    Branches   Missed Branches     Cover
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
client.rs                        1444                67    95.36%         118                13    88.98%         923                35    96.21%           0                 0         -
format.rs                        2172                 3    99.86%         132                 1    99.24%        1292                 1    99.92%           0                 0         -
main.rs                           326               241    26.07%          14                 8    42.86%         225               168    25.33%           0                 0         -
mcp/analytics.rs                  408                 2    99.51%          24                 0   100.00%         331                 0   100.00%           0                 0         -
mcp/mod.rs                        144                55    61.81%          23                15    34.78%         128                65    49.22%           0                 0         -
mcp/prompts.rs                   1908                33    98.27%         126                 6    95.24%        1043                12    98.85%           0                 0         -
mcp/resources.rs                 1317                20    98.48%          93                 1    98.92%         865                 6    99.31%           0                 0         -
mcp/tools.rs                     2146                90    95.81%         116                18    84.48%        1333                47    96.47%           0                 0         -
models.rs                        1079                31    97.13%          78                10    87.18%         762                14    98.16%           0                 0         -
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
TOTAL                           10944               542    95.05%         724                72    90.06%        6902               348    94.96%           0                 0         -

Full HTML report available in CI artifacts.

Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR adopts the Diátaxis documentation framework to provide structured learning paths for NSIP users. The repository had comprehensive technical reference documentation but lacked beginner-friendly tutorials and conceptual explanations. This change adds four types of documentation: learning-oriented tutorials, problem-oriented how-to guides, understanding-oriented explanations, and information-oriented reference materials.

Changes:

  • Added initial documentation in all four Diátaxis quadrants (tutorials, how-to guides, explanations, reference)
  • Reorganized docs/README.md to use Diátaxis framework with clear navigation
  • Created ADR-0003 documenting the framework adoption decision

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 12 comments.

Show a summary per file
File Description
docs/README.md Reorganized documentation index using Diátaxis quadrants with quick start section
docs/adr/0003-adopt-diataxis-documentation-framework.md ADR documenting framework adoption rationale and implementation approach
docs/tutorials/GETTING-STARTED.md 15-minute hands-on tutorial for NSIP API basics
docs/how-to/CONFIGURE-CLIENT.md Guide for customizing HTTP client timeout and retry settings
docs/how-to/COMPARE-ANIMALS.md Guide for comparing genetic traits across multiple animals
docs/explanation/EBV-EXPLAINED.md Conceptual explanation of Estimated Breeding Values
docs/reference/ERROR-HANDLING.md Complete reference for error types and handling patterns

Comment on lines 261 to 262
- [Working with EBV Traits](EBV-TRAITS.md) - Filter and rank animals by genetic traits
- [MCP Integration](MCP-INTEGRATION.md) - Connect AI assistants to NSIP data
Copy link

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These tutorial links reference non-existent files. The files EBV-TRAITS.md and MCP-INTEGRATION.md do not exist in the docs/tutorials directory. Consider either creating these files or removing these links from the "Next Steps" section.

Suggested change
- [Working with EBV Traits](EBV-TRAITS.md) - Filter and rank animals by genetic traits
- [MCP Integration](MCP-INTEGRATION.md) - Connect AI assistants to NSIP data
- Working with EBV Traits — Coming soon: filter and rank animals by genetic traits
- MCP Integration — Coming soon: connect AI assistants to NSIP data

Copilot uses AI. Check for mistakes.
**How-To Guides:**
- [How to Configure Timeout and Retries](../how-to/CONFIGURE-CLIENT.md)
- [How to Compare Animals](../how-to/COMPARE-ANIMALS.md)
- [How to Calculate Inbreeding Coefficient](../how-to/INBREEDING-CHECK.md)
Copy link

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This link references a non-existent file. The file INBREEDING-CHECK.md does not exist in the docs/how-to directory. Consider either creating this file or removing the link.

Suggested change
- [How to Calculate Inbreeding Coefficient](../how-to/INBREEDING-CHECK.md)

Copilot uses AI. Check for mistakes.
Comment on lines 89 to 92
.with_trait_range("Weight", TraitRangeFilter {
min: Some(10.0),
max: Some(50.0),
});
Copy link

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The TraitRangeFilter structure and method name are incorrect. According to crates/models.rs lines 71-77, TraitRangeFilter has fields min: f64 and max: f64 (not Option types). Additionally, the method is with_trait_ranges (plural) which takes a HashMap, not with_trait_range (singular). The correct usage would be: SearchCriteria::new().with_trait_ranges([("Weight".to_string(), TraitRangeFilter { min: 10.0, max: 50.0 })].into())

Suggested change
.with_trait_range("Weight", TraitRangeFilter {
min: Some(10.0),
max: Some(50.0),
});
.with_trait_ranges(
[(
"Weight".to_string(),
TraitRangeFilter {
min: 10.0,
max: 50.0,
},
)]
.into(),
);

Copilot uses AI. Check for mistakes.
## See Also

- [Error Handling Reference](../reference/ERROR-HANDLING.md)
- [API Client Architecture](../explanation/CLIENT-ARCHITECTURE.md)
Copy link

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This link references a non-existent file. The file CLIENT-ARCHITECTURE.md does not exist in the docs/explanation directory. Consider either creating this file or removing the link.

Suggested change
- [API Client Architecture](../explanation/CLIENT-ARCHITECTURE.md)
- API Client Architecture (conceptual overview)

Copilot uses AI. Check for mistakes.
## Further Reading

- [How to Compare Animals](../how-to/COMPARE-ANIMALS.md) - Practical comparison techniques
- [How to Rank Animals](../how-to/RANK-ANIMALS.md) - Multi-trait ranking
Copy link

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This link references a non-existent file. The file RANK-ANIMALS.md does not exist in the docs/how-to directory. Consider either creating this file or removing the link.

Suggested change
- [How to Rank Animals](../how-to/RANK-ANIMALS.md) - Multi-trait ranking
- How to Rank Animals - Multi-trait ranking (coming soon)

Copilot uses AI. Check for mistakes.
// Search for Maternal breed animals (breed_id: 640)
let criteria = SearchCriteria::new()
.with_status("CURRENT")
.with_gender("M"); // Male animals only
Copy link

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The gender filter value should be "Male" (full word) instead of "M". According to the SearchCriteria documentation in crates/models.rs line 49, the gender field expects "Male", "Female", or "Both".

Suggested change
.with_gender("M"); // Male animals only
.with_gender("Male"); // Male animals only

Copilot uses AI. Check for mistakes.
Comment on lines 39 to 45

// Fetch all profiles concurrently
let futures = lpn_ids.iter()
.map(|id| client.search_by_lpn(id));

let profiles = futures::future::try_join_all(futures).await?;

Copy link

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This code example uses the futures crate which is not a dependency of the nsip project. The example should use tokio's join functionality instead. For example, use tokio::try_join! or iterate and await sequentially.

Suggested change
// Fetch all profiles concurrently
let futures = lpn_ids.iter()
.map(|id| client.search_by_lpn(id));
let profiles = futures::future::try_join_all(futures).await?;
// Fetch all profiles (one request per LPN)
let mut profiles = Vec::with_capacity(lpn_ids.len());
for id in &lpn_ids {
profiles.push(client.search_by_lpn(id).await?);
}

Copilot uses AI. Check for mistakes.
Comment on lines 151 to 154
- [How to Calculate Inbreeding Coefficient](INBREEDING-CHECK.md)
- [How to Rank Animals](RANK-ANIMALS.md)
- [Understanding EBVs](../explanation/EBV-EXPLAINED.md)
- [MCP Compare Tool Reference](../MCP.md#compare)
Copy link

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These links reference non-existent files. The files INBREEDING-CHECK.md and RANK-ANIMALS.md do not exist in the docs/how-to directory. Consider either creating these files or removing these links.

Suggested change
- [How to Calculate Inbreeding Coefficient](INBREEDING-CHECK.md)
- [How to Rank Animals](RANK-ANIMALS.md)
- [Understanding EBVs](../explanation/EBV-EXPLAINED.md)
- [MCP Compare Tool Reference](../MCP.md#compare)
- [Understanding EBVs](../explanation/EBV-EXPLAINED.md)
- [MCP Compare Tool Reference](../MCP.md#compare)

Copilot uses AI. Check for mistakes.

### Multi-Trait Selection

Use weighted trait scores (see [How to Rank Animals](../how-to/RANK-ANIMALS.md)).
Copy link

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This link references a non-existent file. The file RANK-ANIMALS.md does not exist in the docs/how-to directory. Consider either creating this file or removing the link.

Copilot uses AI. Check for mistakes.

````rust
let client = NsipClient::builder()
.base_url("http://nsipsearch.nsip.org/api")
Copy link

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example NsipClient::builder().base_url("http://nsipsearch.nsip.org/api") configures the client to talk to the remote NSIP API over plain HTTP instead of HTTPS, exposing all requests and responses to interception and tampering on the network. If users copy this configuration into production code, an on-path attacker could read or modify genetic data and API responses. Update this example to use https:// for remote endpoints (keeping http://localhost only for local testing) so the recommended configuration uses encrypted transport by default.

Suggested change
.base_url("http://nsipsearch.nsip.org/api")
.base_url("https://nsipsearch.nsip.org/api")

Copilot uses AI. Check for mistakes.
Add structured learning paths using the Diátaxis framework:

Tutorials (learning-oriented):
- Getting Started - 15-minute hands-on introduction

How-To Guides (problem-oriented):
- Configure Client - Timeout and retry customization
- Compare Animals - Side-by-side genetic trait comparisons

Explanation (understanding-oriented):
- Understanding EBVs - Breeding value concepts and usage

Reference (information-oriented):
- Error Handling - Complete error type reference

Updated docs/README.md to organize all documentation by framework
quadrants. Added ADR-0003 documenting the framework adoption decision.

Addresses documentation gap identified in repository analysis.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions
Copy link
Contributor

Benchmark Results

No benchmarks configured. Add benchmarks to benches/ directory.

Full results available in CI artifacts.

@github-actions
Copy link
Contributor

Benchmark Results

No benchmarks configured. Add benchmarks to benches/ directory.

Full results available in CI artifacts.

@github-actions
Copy link
Contributor

Code Coverage Report

Overall Coverage: 0%

Summary

Filename                      Regions    Missed Regions     Cover   Functions  Missed Functions  Executed       Lines      Missed Lines     Cover    Branches   Missed Branches     Cover
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
client.rs                        1444                67    95.36%         118                13    88.98%         923                35    96.21%           0                 0         -
format.rs                        2172                 3    99.86%         132                 1    99.24%        1292                 1    99.92%           0                 0         -
main.rs                           326               241    26.07%          14                 8    42.86%         225               168    25.33%           0                 0         -
mcp/analytics.rs                  408                 2    99.51%          24                 0   100.00%         331                 0   100.00%           0                 0         -
mcp/mod.rs                        144                55    61.81%          23                15    34.78%         128                65    49.22%           0                 0         -
mcp/prompts.rs                   1908                33    98.27%         126                 6    95.24%        1043                12    98.85%           0                 0         -
mcp/resources.rs                 1317                20    98.48%          93                 1    98.92%         865                 6    99.31%           0                 0         -
mcp/tools.rs                     2146                90    95.81%         116                18    84.48%        1333                47    96.47%           0                 0         -
models.rs                        1079                31    97.13%          78                10    87.18%         762                14    98.16%           0                 0         -
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
TOTAL                           10944               542    95.05%         724                72    90.06%        6902               348    94.96%           0                 0         -

Full HTML report available in CI artifacts.

Tutorials:
- FIRST-API-QUERY.md, INTERPRETING-RESULTS.md, MCP-SERVER-SETUP.md

How-To Guides:
- BATCH-QUERY.md, EXPORT-JSON.md, FILTER-SEARCH-RESULTS.md
- SCRIPTING-INTEGRATION.md, USE-MCP-TOOLS.md

Explanation:
- BREED-GROUPS-AND-TRAITS.md, DATA-TO-DECISIONS.md
- GENETIC-EVALUATION.md, NSIP-DATA-MODEL.md

Reference:
- CLI.md, CONFIGURATION.md, LIBRARY-API.md, MCP-TOOLS.md

Content sourced from NSIP.org research with accurate breed
groups (USA Hair/Terminal/Maternal/Range), EBV traits, units
(lbs for growth, mm for carcass, % for FEC/reproduction),
and selection indexes (USA MAT-HAIR, USA Terminal).
- README.md: update index with all 22 Diátaxis documents
- EBV-EXPLAINED.md: add MWWT, WFEC, PFEC, SC traits; fix
  units to lbs; add USA MAT-HAIR/Terminal index details
- GETTING-STARTED.md: correct API field names and examples
- COMPARE-ANIMALS.md: fix trait names and method signatures
- CONFIGURE-CLIENT.md: fix cross-reference links
- ERROR-HANDLING.md: expand examples, fix broken links

All growth trait units corrected to lbs to match the NSIP
Search API (crates/mcp/analytics.rs). Added note explaining
LAMBPLAN uses kg internally while NSIP API reports in lbs.
@github-actions
Copy link
Contributor

Benchmark Results

No benchmarks configured. Add benchmarks to benches/ directory.

Full results available in CI artifacts.

@github-actions
Copy link
Contributor

Code Coverage Report

Overall Coverage: 0%

Summary

Filename                      Regions    Missed Regions     Cover   Functions  Missed Functions  Executed       Lines      Missed Lines     Cover    Branches   Missed Branches     Cover
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
client.rs                        1444                67    95.36%         118                13    88.98%         923                35    96.21%           0                 0         -
format.rs                        2172                 3    99.86%         132                 1    99.24%        1292                 1    99.92%           0                 0         -
main.rs                           326               241    26.07%          14                 8    42.86%         225               168    25.33%           0                 0         -
mcp/analytics.rs                  408                 2    99.51%          24                 0   100.00%         331                 0   100.00%           0                 0         -
mcp/mod.rs                        144                55    61.81%          23                15    34.78%         128                65    49.22%           0                 0         -
mcp/prompts.rs                   1908                33    98.27%         126                 6    95.24%        1043                12    98.85%           0                 0         -
mcp/resources.rs                 1317                20    98.48%          93                 1    98.92%         865                 6    99.31%           0                 0         -
mcp/tools.rs                     2146                90    95.81%         116                18    84.48%        1333                47    96.47%           0                 0         -
models.rs                        1079                31    97.13%          78                10    87.18%         762                14    98.16%           0                 0         -
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
TOTAL                           10944               542    95.05%         724                72    90.06%        6902               348    94.96%           0                 0         -

Full HTML report available in CI artifacts.

- Add YAML frontmatter (status, date) to ADR-0001, ADR-0002, ADR-0003
- Narrow adrscope validation pattern to [0-9]*.md to skip README.md
- Fix line-length lint on checkout action comment
- Add ADR-0003 to README index
@github-actions
Copy link
Contributor

Benchmark Results

No benchmarks configured. Add benchmarks to benches/ directory.

Full results available in CI artifacts.

@github-actions
Copy link
Contributor

Code Coverage Report

Overall Coverage: 0%

Summary

Filename                      Regions    Missed Regions     Cover   Functions  Missed Functions  Executed       Lines      Missed Lines     Cover    Branches   Missed Branches     Cover
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
client.rs                        1444                67    95.36%         118                13    88.98%         923                35    96.21%           0                 0         -
format.rs                        2172                 3    99.86%         132                 1    99.24%        1292                 1    99.92%           0                 0         -
main.rs                           326               241    26.07%          14                 8    42.86%         225               168    25.33%           0                 0         -
mcp/analytics.rs                  408                 2    99.51%          24                 0   100.00%         331                 0   100.00%           0                 0         -
mcp/mod.rs                        144                55    61.81%          23                15    34.78%         128                65    49.22%           0                 0         -
mcp/prompts.rs                   1908                33    98.27%         126                 6    95.24%        1043                12    98.85%           0                 0         -
mcp/resources.rs                 1317                20    98.48%          93                 1    98.92%         865                 6    99.31%           0                 0         -
mcp/tools.rs                     2146                90    95.81%         116                18    84.48%        1333                47    96.47%           0                 0         -
models.rs                        1079                31    97.13%          78                10    87.18%         762                14    98.16%           0                 0         -
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
TOTAL                           10944               542    95.05%         724                72    90.06%        6902               348    94.96%           0                 0         -

Full HTML report available in CI artifacts.

Add all required schema fields: title, description, type,
category, tags, status, created, updated, author, project,
technologies, and audience.
@github-actions
Copy link
Contributor

Benchmark Results

No benchmarks configured. Add benchmarks to benches/ directory.

Full results available in CI artifacts.

@github-actions
Copy link
Contributor

Code Coverage Report

Overall Coverage: 0%

Summary

Filename                      Regions    Missed Regions     Cover   Functions  Missed Functions  Executed       Lines      Missed Lines     Cover    Branches   Missed Branches     Cover
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
client.rs                        1444                67    95.36%         118                13    88.98%         923                35    96.21%           0                 0         -
format.rs                        2172                 3    99.86%         132                 1    99.24%        1292                 1    99.92%           0                 0         -
main.rs                           326               241    26.07%          14                 8    42.86%         225               168    25.33%           0                 0         -
mcp/analytics.rs                  408                 2    99.51%          24                 0   100.00%         331                 0   100.00%           0                 0         -
mcp/mod.rs                        144                55    61.81%          23                15    34.78%         128                65    49.22%           0                 0         -
mcp/prompts.rs                   1908                33    98.27%         126                 6    95.24%        1043                12    98.85%           0                 0         -
mcp/resources.rs                 1317                20    98.48%          93                 1    98.92%         865                 6    99.31%           0                 0         -
mcp/tools.rs                     2146                90    95.81%         116                18    84.48%        1333                47    96.47%           0                 0         -
models.rs                        1079                31    97.13%          78                10    87.18%         762                14    98.16%           0                 0         -
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
TOTAL                           10944               542    95.05%         724                72    90.06%        6902               348    94.96%           0                 0         -

Full HTML report available in CI artifacts.

@zircote zircote merged commit a56b918 into main Feb 16, 2026
32 checks passed
@zircote zircote deleted the docs/diataxis-framework branch February 16, 2026 23:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: adopt Diátaxis framework for user documentation

3 participants